home *** CD-ROM | disk | FTP | other *** search
/ QuickTime 1.0 for Developers / QuickTime 1.0 for Developers.iso / Programming Stuff / Interfaces / Oldstyle C Interfaces / PreviewComponent.h < prev    next >
C/C++ Source or Header  |  1991-09-06  |  16KB  |  390 lines
  1. /*
  2.     File:        PreviewComponent.h
  3.     Written by:    Chris Thorman
  4.     Copyright:    © 1991 by Apple Computer, Inc., all rights reserved.
  5. */
  6.  
  7. #ifndef _PreviewComponentHeader_
  8. #define _PreviewComponentHeader_
  9.  
  10. #include "Components.h"                    /* Components. */
  11. #include "Image Compression.h"            /* For ProgressProcPtr */
  12.  
  13. #include <StandardFile.h>                /* For StandardFileReply.h */
  14.  
  15. /************************************************************************************
  16. *                                                                                    *
  17. * Thumbnail Resources                                                                *
  18. *                                                                                    *
  19. * Pre-computed preview information is stored in a document's resource fork.            *
  20. * Typically, the information consists of a PRVL resource (ID = 0) which is            *
  21. * a list of other previewing-related resources found in the file.  Normally,        *
  22. * the first (and usually, only) resource in the list is a PICT resource that        *
  23. * was created by the image compression manager.                                        *
  24. *                                                                                    *
  25. *                                                                                    *
  26. ************************************************************************************/
  27.  
  28. typedef struct ResourceDesc {
  29.     ResType            resourceType;
  30.     short            resourceId;
  31. };
  32. typedef struct ResourceDesc    ResourceDesc;
  33.  
  34. typedef    struct ThumbnailList {
  35.     unsigned long    date;                /* When the resource was last modified. */
  36.     short            version;            /* Always 3 when using version shown here. */
  37.     ResType            prevComponentType;    /* The type of Preview Component that made the preview */
  38.     Str31            fileTypeDesc;        /* Vernacular description of the type of the file */
  39.     short            fileTypeDescScript;    /* Script code for the file desc string */
  40.     short            count;                /* number of elements in the following array */
  41.     ResourceDesc    resources[1];        /* an array of resource descriptions */
  42. };
  43.  
  44. typedef struct ThumbnailList    ThumbnailList;
  45. typedef ThumbnailList *         ThumbnailListPtr;
  46. typedef ThumbnailListPtr *         ThumbnailListHandle;
  47.  
  48.  
  49. /************************************************************************************
  50. *                                                                                    *
  51. *    Looking up Preview Components                                                  *
  52. *                                                                                    *
  53. * You will typically use preview components to add preview information to a            *
  54. *                                                                                    *
  55. ************************************************************************************/
  56.  
  57.  
  58. /* The component type */
  59.  
  60. #define PreviewComponentType        'prvt'
  61.  
  62. /* The subtypes of the preview components provided by Apple */
  63.  
  64. #define FileInfoPrevCompSubType        'finf'        /* Shows file type (from PRVL) and size */
  65. #define PICTPrevCompSubType            'PICT'        /* Creates / Shows PICT thumbnails */
  66. #define MoviePrevCompSubType        'MooV'        /* Creates thumbnails for movie files */
  67.  
  68. typedef ComponentInstance Previewer;
  69.  
  70. /* Preview Component Procedure Selectors */
  71.  
  72. enum {
  73. prevComponentCreatePreviewRefNum = 2,
  74. prevComponentGetPreviewData,
  75. prevComponentAddPreviewRefNum = 5,
  76.  
  77. prevComponentStartPreviewing = 11,
  78. prevComponentDoDraw,
  79. prevComponentTimeSlice ,
  80. prevComponentDoMouseDown,
  81. prevComponentLastCall
  82. };
  83.  
  84. /************************************************************************************
  85. *                                                                                    *
  86. *    Using Preview Components to Create Previews                                    *
  87. *                                                                                    *
  88. * You will typically use preview components to add preview information to a            *
  89. * document that your program has created.  You'll use the component manager to         *
  90. * get a component instance that matches the type of the preview that you want to    *
  91. * add (PICT or Movie are the only two currently supplied by Apple), then you'll        *
  92. * call the CreatePreview routine if you want the component to create the preview    *
  93. * information and add it to the file, or AddPreview if you have already generated    *
  94. * the preview data and simply want it placed into the file (for instance, if you    *
  95. * have already created the thumbnail PICT and simply want it added.)                *
  96. *                                                                                    *
  97. ************************************************************************************/
  98.  
  99. /* Data structure used to specify the file type when creating a preview.  TheString is
  100.     a string which the user will see when the preview appears in StandardFile.  It
  101.     describes the file type in the vernacular (for example ``Picture File'').  scriptCode
  102.     is the script system to be used to display the string.  Usually this will be the
  103.     system script.  In any of the component calls that take a pointer to a 
  104.     Str31WithScript structure, you may pass NIL and the
  105.     component will use its own string (localized) and script code.
  106.     
  107.     Mainly, you will need to use this structure when adding a PICT preview to a
  108.     document that is not a PICT file, for instance, ``MacWrite Document'', or ``TeachText
  109.     Document''.
  110.     
  111.     */
  112.  
  113. struct Str31WithScript
  114. {
  115.     Str31        theString;
  116.     short        scriptCode;
  117. };
  118. typedef struct Str31WithScript Str31WithScript, *Str31WithScriptPtr, **Str31WithScriptHandle;
  119.  
  120.  
  121. /* PreviewerCreatePreviewForResRefNum is called to create a preview for a file.
  122.  
  123.     The file that you specify should be the same type as the preview component.
  124.     Use the Apple PICT component to create previews for PICT files.
  125.     Use the Apple Movie component to create previews for Movie files.
  126.         
  127.     You do not have to call any of the other routines to use this one.
  128.         
  129.     If removeOldPreviews is true, then any pre-existing preview data in the file will
  130.     be removed before the new preview is added.  This includes any resources that
  131.     are listed in the PRVL resource, no matter which preview component put them there.
  132.     
  133.     If removeOldPreviews is false, then the appropriate resources will be added to 
  134.     the file and their description will be added to the end of the PRVL resource.
  135.     
  136.     progressProc is a procedure that will be called periodically to indicate progress.
  137.     See the definition of ProgressProcPtr in the Image Compression Manager for details.
  138.     
  139.     If fileTypeDescription is not 0, then the string and script code that it points to 
  140.     will be placed into the thumbnail list that is created (in the fileTypeDesc and
  141.     fileTypeDescScript fields).
  142.  
  143.     If the component opens the file's data fork, it will be opened for read
  144.     access only.
  145.  
  146.     The resRefNum argument is the reference number for the resource fork of the 
  147.     file which has already been opened for write access.
  148.     
  149.     */
  150.  
  151.  
  152. pascal ComponentResult
  153. PreviewerCreatePreviewForResRefNum(Previewer p, 
  154.                                     short resRefNum, 
  155.                                     FSSpecPtr theFile, 
  156.                                     Boolean removeOldPreviews,
  157.                                     Str31WithScriptPtr fileTypeDescription,
  158.                                     ProgressProcRecordPtr progressProc 
  159.                                       )
  160.             = ComponentCallNow( prevComponentCreatePreviewRefNum, 16);
  161.  
  162. /* PreviewerGetPreviewData creates preview data for a file without actually adding
  163.     the data to the file or modifying the file in any way.  The file is opened
  164.     read only.
  165.  
  166.     The Handles passed in previewData and auxData should have already
  167.     been created in the application heap.  Any data in them will be lost and
  168.     they will be resized as necessary.  The caller is responsible for disposing them.
  169.     
  170.     auxData is reserved for use by components that store their previews in
  171.     two chunks rather than one.
  172.  
  173.     The type of the data depends on the type of the preview component.  For 
  174.     instance, the PICT preview component returns a picHandle to a thumbnail-sized
  175.     picture in previewData, and leaves auxData untouched.
  176.     */
  177. pascal ComponentResult
  178. PreviewerGetPreviewData(Previewer p,         
  179.                         FSSpecPtr theFile, 
  180.                         Handle previewData,
  181.                         Handle auxData,
  182.                         ProgressProcRecordPtr progressProc 
  183.                         )
  184.         = ComponentCallNow( prevComponentGetPreviewData, 16);
  185.  
  186. /* PreviewerAddPreviewDataRefNum adds a preview that you have already created to a file.
  187.  
  188.     It is called by a program that has already calculated a preview
  189.     for a file and simply wishes the data to be added to the file.
  190.     For instance, a program may create its own PICT thumbnail and then ask the PICT 
  191.     previewer to add that to a file.
  192.     
  193.     The type of the file does NOT have to match the type of the preview component.
  194.     Use this routine to add a PICT thumbnail to a file of any type,
  195.     such as a movie file or a text document.
  196.         
  197.     This call should result in the data contained in the previewData handle being
  198.     added as a resource in the file's resource fork.  The type of the resource will
  199.     match the subtype of the preview component.  For instance, the PICT component
  200.     adds PICTs.  There is no way to specify a particular ID for the resource that
  201.     is added.
  202.     
  203.     Different preview components may have slightly different behaviors in response
  204.     to this call.  An extra argument, auxData, has been provided for components that
  205.     need to store two chunks of data.  It is typically ignored.  Currently, it is
  206.     ignored by the preview components provided by Apple.
  207.  
  208.     You do not have to call any of the other routines to use this one.
  209.         
  210.     If removeOldPreviews is true, then any pre-existing preview data in the file will
  211.     be removed before the new preview is added.  This includes any resources that
  212.     are listed in the PRVL resource, no matter which preview component put them there.
  213.     
  214.     If removeOldPreviews is false, then the appropriate resources will be added to 
  215.     the file and their description will be added to the end of the PRVL resource.
  216.     
  217.     progressProc is a procedure that will be called periodically to indicate progress.
  218.     See the definition of ProgressProcPtr in the Image Compression Manager for details.
  219.  
  220.     If fileTypeDescription is not 0, then the string and script code that it points to 
  221.     will be placed into the thumbnail list that is created (in the fileTypeDesc and
  222.     fileTypeDescScript fields).
  223.     
  224.     This routine will not open the data fork of the file; the file does not even
  225.     need to have one.
  226.     
  227.     The resRefNum argument is the reference number for the resource fork of the 
  228.     file which has already been opened for write access.
  229.  
  230.     */
  231.  
  232.  
  233. pascal ComponentResult
  234. PreviewerAddPreviewDataRefNum(Previewer p,         
  235.                             short resRefNum,                        
  236.                             FSSpecPtr theFile, 
  237.                             Boolean removeOldPreviews,
  238.                             Str31WithScriptPtr fileTypeDescription,
  239.                             Handle previewData,
  240.                             Handle auxData
  241.                               )
  242.         = ComponentCallNow( prevComponentAddPreviewRefNum, 20);
  243.  
  244. /************************************************************************************
  245. *                                                                                    *
  246. *    Using Preview Components to Show Previews                                        *
  247. *                                                                                    *
  248. * If your program needs to show previews, then you should use the component            *
  249. * routines described below.  If you are writing a preview component, then you will    *
  250. * need to implement the appropriate routines so that the previews can be viewed in    *
  251. * StandardFile.                                                                        *
  252. *                                                                                    *
  253. ************************************************************************************/
  254.  
  255. /* This structure is the first argument to the following five component calls.
  256.     It describes the file that the component is being asked to show a preview for.
  257.  
  258.     If the file has a resource fork, then it will be already have been opened for
  259.     read access and the refNum passed in the PreviewStatus record.  If the file
  260.     had a thumbnail list (PRVL resource), then a resource handle to it will be
  261.     in PRVLHandle.  
  262.     */
  263.     
  264. struct PreviewStatusRec {
  265.     StandardFileReply    fileInfo;        /* See StandardFile.h */
  266.     long                fileSize;        /* File size in bytes */
  267.     short                resRefNum;        /* resource RefNum or 0 if no resource fork */
  268.     ThumbnailListHandle    PRVLHandle;        /* handle to the PRVL or 0 if none */ 
  269.     };
  270. typedef struct PreviewStatusRec PreviewStatusRec, *PreviewStatusPtr, **PreviewStatusHandle;
  271.  
  272.  
  273. /* PreviewerStartPreviewing is called to start previewing a file.  
  274.     
  275.     It may be called under two distinct circumstances: 
  276.     
  277.     1) when the file has a PRVL which was created by this component,
  278.         in which case the component will try to use its own pre-calculated
  279.         preview resources to show the preview, or
  280.     
  281.     2) when the file's type matches the type of the component, 
  282.         in which case the component will either try to preview the file by 
  283.         reading information directly from its data or resource forks or it
  284.         will return prevComponentCouldGeneratePreviewForThisFile, which means
  285.         that the component believes it could generate a preview for the file
  286.         if you were to call PreviewerCreatePreviewForFile.
  287.     
  288.     If this routine returns noErr, then you MUST call PreviewerLastCall before
  289.     starting to preview a different file, creating a preview for a file, or closing
  290.     the preview component.  If it returns any other value, then you should NOT
  291.     call PreviewerLastCall.
  292.             
  293.     The component assumes that the grafPort specified in the window parameter is
  294.     the current grafport.
  295.  
  296.     boundsRect describes the rectangle that can be used to show the preview in. Typically, 
  297.     this is a 120x120 rectangle.  Its coordinates are in terms of the current grafport.  
  298.     
  299.     If the component returns noErr, then it should set the coordinates of boundsRect
  300.     to be the rectangle which it is actually using to draw the preview in.  The
  301.     modified boundsRect may be the same size as the original or smaller in any
  302.     dimension, but may not include any area outside the rectangle that was passed in.
  303.         
  304.     If the component returns true in NeedInitialUpdate, then a DoDraw call
  305.     will be generated on the next time the window is updated (i.e. InvalRect will
  306.     be called).  If false is returned in NeedInitialUpdate, then a DoDraw call
  307.     will only be called if the window needs updating during the normal course
  308.     of user actions (obscuring by another window, changing screen depth, etc.)
  309.     
  310.     */
  311.  
  312. pascal ComponentResult
  313. PreviewerStartPreviewing(Previewer p, 
  314.                         PreviewStatusPtr status, 
  315.                         WindowPtr window, 
  316.                         Rect * boundsRect, 
  317.                         Boolean * NeedInitialUpdate
  318.                         )
  319.             = ComponentCallNow( prevComponentStartPreviewing, 16 );
  320.  
  321. enum {
  322. prevComponentCantPreviewThisFile                 = -9999,
  323. prevComponentCouldGeneratePreviewForThisFile    = -9998
  324. };
  325.  
  326. /* 
  327.     The following three routines are only called between successful calls 
  328.     to the StartPreviewing and LastCall routines.
  329.  
  330.     All drawing must stay within the boundsRect that was originally passed during
  331.     PreviewerStartPreviewing.  
  332.     
  333.     The grafport will be the same as during the StartPreviewing call.
  334.     */
  335.  
  336. /* PreviewerDoDraw is called whenever the preview rectangle needs to be drawn.
  337.     */
  338.     
  339. pascal ComponentResult
  340. PreviewerDoDraw(Previewer p, PreviewStatusPtr status)
  341.             = ComponentCallNow( prevComponentDoDraw, 4 );
  342.  
  343. /* PreviewerDoMouseDown is called if the user clicks on the preview rectangle.
  344.     */
  345.  
  346. pascal ComponentResult
  347. PreviewerDoMouseDown(Previewer p, PreviewStatusPtr status)
  348.             = ComponentCallNow( prevComponentDoMouseDown, 4 );
  349.  
  350. /* PreviewerTimeSlice is called whenever there is idle time.
  351.  
  352.     Use this routine to update temporal previews (such as sounds or animations).
  353.     
  354.     If your component does not need time slice calls, it should return
  355.     prevComponentDontNeedTimeSlice when it is called.
  356.     
  357.     */
  358.     
  359. pascal ComponentResult
  360. PreviewerTimeSlice(Previewer p, PreviewStatusPtr status)
  361.             = ComponentCallNow( prevComponentTimeSlice, 4 );
  362.  
  363. enum {
  364. prevComponentDontNeedTimeSlice                    = -9993
  365. };
  366.  
  367.  
  368. /* PreviewerLastCall is called when it is time to stop previewing a file.
  369.  
  370.     You can't do any drawing during this call.  You should free any resources
  371.     that you may have read in from the file and close the data fork of the file, if
  372.     you opened it during previewing.
  373.     
  374.     This is not the same as the CloseComponent call -- the component does not free
  375.     any of its internal storage, rather, it cleans up anything it allocated in order
  376.     to preview the current file.  The component does not close the file's resource
  377.     fork (stored in status->resRefNum), but it does close any other paths that
  378.     it opened during StartPreviewing.
  379.     
  380.     */
  381.     
  382. pascal ComponentResult
  383. PreviewerLastCall(Previewer p, PreviewStatusPtr status)
  384.             = ComponentCallNow( prevComponentLastCall, 4 );
  385.  
  386.  
  387. #endif _PreviewComponentHeader_
  388.  
  389.  
  390.